Inside Macintosh: QuickDraw GX Objects /

Chapter 7 - View-Related Objects / View-Related Objects Reference

View Device Functions / Hit-Testing a Shape on a Device

GXHitTestDevice

You can use the GXHitTestDevice function to determine whether a point in device space is within a given tolerance of a shape displayed on that device.

gxShape GXHitTestDevice(gxShape target, gxViewPort port, 
                        gxViewDevice device, const gxPoint *test, 
                        const gxPoint *tolerance);

target

A reference to the shape to hit-test.

port

A reference to a view port that the shape is drawn to.

device

A reference to the view device on which the shape is drawn.

test

A pointer to a point structure specifying the location, in device coordinates (pixels), to hit-test the shape against.

tolerance

A pointer to a point structure specifying a rectangular shape whose size specifies the distance, in pixels, from the target shape that the test point can be and still be considered a successful hit.

function result

A reference to the target shape if the shape was hit; otherwise nil.

DESCRIPTION

The GXHitTestDevice function returns the target shape within the specified view port if the hit is successful, otherwise it returns nil. All clipping, from transform through view port and view device, is taken into account in determining whether a hit is possible.

The test point represents a pixel location in view device coordinates. The tolerance represents a rectangular area of pixels, defining the "radius" of the total tolerance area. You can think of four such rectangles as making up a larger rectangle centered on the hit point; if the distance from the hit point to the shape is within that larger rectangle, the
hit is considered successful.

Negative values for the tolerance are permitted.

If the port parameter is set to 0, all view ports on the view device are tested. If the device parameter is set to 0, all view devices intersected by the view port are tested. If both port and device parameters are set to 0, all view ports that the shape is drawn to and all view devices drawn to by the target shape are tested.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
parameter_is_nil	(debugging version)

SEE ALSO

To hit-test individual parts of a shape's geometry, use the GXHitTestShape function, described in the chapter "Shape Objects" in this book. To hit-test the parts of a picture shape, use the GXHitTestPicture function, described in the picture shapes chapter of Inside Macintosh: QuickDraw GX Graphics. To hit-test the text of a layout shape, use the GXHitTestLayout function, described in the layout carets chapter of Inside Macintosh: QuickDraw GX Typography.

For more information on GXHitTestDevice and how it relates to the other hit-testing functions, see "Hit-Testing a Shape on a Device" on page 7-60.